<!-- HTML header for doxygen 1.8.3.1-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.3.1"/>
<title>AngelScript: Calling a script function</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="test/javascript" src="touch.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="aslogo_small.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">AngelScript
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.3.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('doc_call_script_func.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Calling a script function </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="doc_call_script_1"></a>
Preparing context and executing the function</h1>
<p>Normally a script function is executed in a few steps:</p>
<ol>
<li>
Prepare the context </li>
<li>
Set the function arguments </li>
<li>
Execute the function </li>
<li>
Retrieve the return value </li>
</ol>
<p>The code for this might look something like this:</p>
<div class="fragment"><div class="line"><span class="comment">// Get a script context instance. Usually you&#39;ll want to reuse a previously</span></div>
<div class="line"><span class="comment">// created instance to avoid the overhead of allocating the instance with</span></div>
<div class="line"><span class="comment">// each call.</span></div>
<div class="line"><a class="code" href="classas_i_script_context.html" title="The interface to the virtual machine.">asIScriptContext</a> *ctx = engine-&gt;<a class="code" href="classas_i_script_engine.html#a2630e1cd03ffab0fee9b820bf0afe42a" title="Creates a new script context.">CreateContext</a>();</div>
<div class="line"></div>
<div class="line"><span class="comment">// Obtain the function from the module. This should preferrably  </span></div>
<div class="line"><span class="comment">// be cached if the same function is called multiple times.</span></div>
<div class="line"><a class="code" href="classas_i_script_function.html" title="The interface for a script function description.">asIScriptFunction</a> *func = engine-&gt;<a class="code" href="classas_i_script_engine.html#a9f7cdc52b59034e6e55eb8a56b427aa4" title="Return an interface pointer to the module.">GetModule</a>(module_name)-&gt;<a class="code" href="classas_i_script_module.html#ab4754d55d8667aefbed135b4794d461b" title="Returns the function by its declaration.">GetFunctionByDecl</a>(function_declaration);</div>
<div class="line"></div>
<div class="line"><span class="comment">// Prepare() must be called to allow the context to prepare the stack</span></div>
<div class="line">ctx-&gt;<a class="code" href="classas_i_script_context.html#a43976f42dfc6c1af23e132d36265173a" title="Prepares the context for execution of the function.">Prepare</a>(func);</div>
<div class="line"></div>
<div class="line"><span class="comment">// Set the function arguments</span></div>
<div class="line">ctx-&gt;<a class="code" href="classas_i_script_context.html#a14cac831c1b419f552ca62a239dfcf45" title="Sets a 32-bit integer argument value.">SetArgDWord</a>(...);</div>
<div class="line"></div>
<div class="line"><span class="keywordtype">int</span> r = ctx-&gt;<a class="code" href="classas_i_script_context.html#a8e52894432737acac2e1a422e496bf84" title="Executes the prepared function.">Execute</a>();</div>
<div class="line"><span class="keywordflow">if</span>( r == <a class="code" href="angelscript_8h.html#a867f14b4137dd4602fda1e616b217a69a6d3730dd7a91aff81cafaaca4e93efaa" title="The context has successfully completed the execution.">asEXECUTION_FINISHED</a> )</div>
<div class="line">{</div>
<div class="line">  <span class="comment">// The return value is only valid if the execution finished successfully</span></div>
<div class="line">  <a class="code" href="angelscript_8h.html#a5428f0c940201e5f3bbb28304aeb81bc" title="32 bit unsigned integer">asDWORD</a> ret = ctx-&gt;<a class="code" href="classas_i_script_context.html#a43cd2fb72685aef96e8ddc622c9621bf" title="Returns the 32-bit return value.">GetReturnDWord</a>();</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line"><span class="comment">// Release the context when you&#39;re done with it</span></div>
<div class="line">ctx-&gt;<a class="code" href="classas_i_script_context.html#a1b13a5f3e58627e9ff4300c0c6f0f3cf" title="Decrease reference counter.">Release</a>();</div>
</div><!-- fragment --><p>If your application allows the execution to be suspended, either by using the callback function or registering a function that allow the script to manually suspend the execution, then the execution function may return before finishing with the return code asEXECUTION_SUSPENDED. In that case you can later resume the execution by simply calling the execution function again.</p>
<p>Note that the return value retrieved with GetReturnValue() is only valid if the script function returned successfully, i.e. if Execute() returned asEXECUTION_FINISHED.</p>
<h1><a class="anchor" id="doc_call_script_2"></a>
Passing and returning primitives</h1>
<p>When calling script functions that take arguments, the values of these arguments must be set after the call to Prepare() and before Execute(). The arguments are set using a group of SetArg methods:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> SetArgDWord(<span class="keywordtype">int</span> arg, <a class="code" href="angelscript_8h.html#a5428f0c940201e5f3bbb28304aeb81bc" title="32 bit unsigned integer">asDWORD</a> value);</div>
<div class="line"><span class="keywordtype">int</span> SetArgQWord(<span class="keywordtype">int</span> arg, <a class="code" href="angelscript_8h.html#a10aea5de212e440ffd6ec8fc0b17563d" title="64 bit unsigned integer">asQWORD</a> value);</div>
<div class="line"><span class="keywordtype">int</span> SetArgFloat(<span class="keywordtype">int</span> arg, <span class="keywordtype">float</span> value);</div>
<div class="line"><span class="keywordtype">int</span> SetArgDouble(<span class="keywordtype">int</span> arg, <span class="keywordtype">double</span> value);</div>
<div class="line"><span class="keywordtype">int</span> SetArgByte(<span class="keywordtype">int</span> arg, <a class="code" href="angelscript_8h.html#a48b3da7121b3abb56bff63b3beb0df63" title="8 bit unsigned integer">asBYTE</a> value);</div>
<div class="line"><span class="keywordtype">int</span> SetArgWord(<span class="keywordtype">int</span> arg, <a class="code" href="angelscript_8h.html#a340da175136fbe283932fa3c3442cea0" title="16 bit unsigned integer">asWORD</a> value);</div>
</div><!-- fragment --><p><code>arg</code> is the argument number, where the first argument is on 0, the second on 1, and so on. <code>value</code> is the value of the argument. What method to use is determined by the type of the parameter. For primitive types you can use any of these. If the parameter type is a reference to a primitive type it is recommended to use the SetArgDWord() method and pass the pointer as the value. For non-primitive types the method SetArgObject() should be used, which will be described in the next section.</p>
<div class="fragment"><div class="line"><span class="comment">// The context has been prepared for a script </span></div>
<div class="line"><span class="comment">// function with the following signature:</span></div>
<div class="line"><span class="comment">// int function(int, double, bool, int &amp;out)</span></div>
<div class="line"></div>
<div class="line"><span class="comment">// Put the arguments on the context stack, starting with the first one</span></div>
<div class="line">ctx-&gt;<a class="code" href="classas_i_script_context.html#a14cac831c1b419f552ca62a239dfcf45" title="Sets a 32-bit integer argument value.">SetArgDWord</a>(0, 1);</div>
<div class="line">ctx-&gt;<a class="code" href="classas_i_script_context.html#acbdddda3b80c37b70b8fd35c8e7383b9" title="Sets a double argument value.">SetArgDouble</a>(1, 3.141592);</div>
<div class="line">ctx-&gt;<a class="code" href="classas_i_script_context.html#ac5ac8ce5bb209f43d4da620db5d271da" title="Sets an 8-bit argument value.">SetArgByte</a>(2, <span class="keyword">true</span>);</div>
<div class="line"><span class="keywordtype">int</span> val;</div>
<div class="line">ctx-&gt;<a class="code" href="classas_i_script_context.html#aa8de8f21dfbb2cdf0becbabaa3e883ed" title="Sets the address of a reference or handle argument.">SetArgAddress</a>(3, &amp;val);</div>
</div><!-- fragment --><p>Once the script function has been executed the return value is retrieved in a similar way using the group of GetReturn methods:</p>
<div class="fragment"><div class="line"><a class="code" href="angelscript_8h.html#a5428f0c940201e5f3bbb28304aeb81bc" title="32 bit unsigned integer">asDWORD</a> GetReturnDWord();</div>
<div class="line"><a class="code" href="angelscript_8h.html#a10aea5de212e440ffd6ec8fc0b17563d" title="64 bit unsigned integer">asQWORD</a> GetReturnQWord();</div>
<div class="line"><span class="keywordtype">float</span>   GetReturnFloat();</div>
<div class="line"><span class="keywordtype">double</span>  GetReturnDouble();</div>
<div class="line"><a class="code" href="angelscript_8h.html#a48b3da7121b3abb56bff63b3beb0df63" title="8 bit unsigned integer">asBYTE</a>  GetReturnByte();</div>
<div class="line"><a class="code" href="angelscript_8h.html#a340da175136fbe283932fa3c3442cea0" title="16 bit unsigned integer">asWORD</a>  GetReturnWord();</div>
</div><!-- fragment --><p>Note that you must make sure the returned value is in fact valid, for example if the script function was interrupted by a script exception the value would not be valid. You do this by verifying the return code from Execute() or GetState(), where the return code should be asEXECUTION_FINISHED.</p>
<h1><a class="anchor" id="doc_call_script_3"></a>
Passing and returning objects</h1>
<p>Passing registered object types to a script function is done in a similar way to how primitive types are passed. The function to use is SetArgObject():</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> SetArgObject(<span class="keywordtype">int</span> arg, <span class="keywordtype">void</span> *<span class="keywordtype">object</span>);</div>
</div><!-- fragment --><p><code>arg</code> is the argument number, just like the other SetArg methods. <code>object</code> is a pointer to the object you wish to pass.</p>
<p>This same method is used both for parameters passed by value and for those passed by reference. The library will automatically make a copy of the object if the parameter is defined to be passed by value.</p>
<div class="fragment"><div class="line"><span class="comment">// The complex object we wish to pass to the script function</span></div>
<div class="line">CObject obj;</div>
<div class="line"></div>
<div class="line"><span class="comment">// Pass the object to the function</span></div>
<div class="line">ctx-&gt;<a class="code" href="classas_i_script_context.html#a09044a12dfb2d44d19bd8a4025cb814d" title="Sets the object argument value.">SetArgObject</a>(0, &amp;obj);</div>
</div><!-- fragment --><p>Getting an object returned by a script function is done in a similar way, using GetReturnObject():</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> *GetReturnObject();</div>
</div><!-- fragment --><p>This method will return a pointer to the object returned by the script function. The library will still hold a reference to the object, which will only be freed as the context is released.</p>
<div class="fragment"><div class="line"><span class="comment">// The object where we want to store the return value</span></div>
<div class="line">CObject obj;</div>
<div class="line"></div>
<div class="line"><span class="comment">// Execute the function</span></div>
<div class="line"><span class="keywordtype">int</span> r = ctx-&gt;<a class="code" href="classas_i_script_context.html#a8e52894432737acac2e1a422e496bf84" title="Executes the prepared function.">Execute</a>();</div>
<div class="line"><span class="keywordflow">if</span>( r == <a class="code" href="angelscript_8h.html#a867f14b4137dd4602fda1e616b217a69a6d3730dd7a91aff81cafaaca4e93efaa" title="The context has successfully completed the execution.">asEXECUTION_FINISHED</a> )</div>
<div class="line">{</div>
<div class="line">  <span class="comment">// Get a pointer to the returned object and copy it to our object</span></div>
<div class="line">  obj = *(CObject*)ctx-&gt;<a class="code" href="classas_i_script_context.html#a6d5739fac9c90bcd0fea55d01841d43a" title="Return a pointer to the returned object.">GetReturnObject</a>();</div>
<div class="line">}</div>
</div><!-- fragment --><p>It is important to make a copy of the returned object, or if it is managed by reference counting add a reference to it. If this is not done the pointer obtained with GetReturnObject() will be invalidated as the context is released, or reused for another script function call.</p>
<h1><a class="anchor" id="doc_call_script_4"></a>
Exception handling</h1>
<p>If the script performs an illegal action, e.g. calling a method on a null handle, then the script engine will throw a script exception. The virtual machine will then abort the execution and the <a class="el" href="classas_i_script_context.html#a8e52894432737acac2e1a422e496bf84">Execute</a> method will return with the value <a class="el" href="angelscript_8h.html#a867f14b4137dd4602fda1e616b217a69aa3d548fa7d2278d848e50222b700c6c8">asEXECUTION_EXCEPTION</a>.</p>
<p>At this time it is possible to obtain information about the exception through the <a class="el" href="classas_i_script_context.html">asIScriptContext</a>'s methods. Example:</p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> PrintExceptionInfo(<a class="code" href="classas_i_script_context.html" title="The interface to the virtual machine.">asIScriptContext</a> *ctx)</div>
<div class="line">{</div>
<div class="line">  <a class="code" href="classas_i_script_engine.html" title="The engine interface.">asIScriptEngine</a> *engine = ctx-&gt;<a class="code" href="classas_i_script_context.html#a07f12016c5435aec5b63449abb6e4d8d" title="Returns a pointer to the engine.">GetEngine</a>();</div>
<div class="line"></div>
<div class="line">  <span class="comment">// Determine the exception that occurred</span></div>
<div class="line">  printf(<span class="stringliteral">&quot;desc: %s\n&quot;</span>, ctx-&gt;<a class="code" href="classas_i_script_context.html#a46e2411bc84e99f57e7d9fe2374bb479" title="Returns the exception string text.">GetExceptionString</a>());</div>
<div class="line"></div>
<div class="line">  <span class="comment">// Determine the function where the exception occurred</span></div>
<div class="line">  <span class="keyword">const</span> <a class="code" href="classas_i_script_function.html" title="The interface for a script function description.">asIScriptFunction</a> *<span class="keyword">function</span> = ctx-&gt;<a class="code" href="classas_i_script_context.html#a8e59aceec42080d29e08b44460ceb8b3" title="Returns the function where the exception occurred.">GetExceptionFunction</a>();</div>
<div class="line">  printf(<span class="stringliteral">&quot;func: %s\n&quot;</span>, function-&gt;GetDeclaration());</div>
<div class="line">  printf(<span class="stringliteral">&quot;modl: %s\n&quot;</span>, function-&gt;GetModuleName());</div>
<div class="line">  printf(<span class="stringliteral">&quot;sect: %s\n&quot;</span>, function-&gt;GetScriptSectionName());</div>
<div class="line"></div>
<div class="line">  <span class="comment">// Determine the line number where the exception occurred</span></div>
<div class="line">  printf(<span class="stringliteral">&quot;line: %d\n&quot;</span>, ctx-&gt;<a class="code" href="classas_i_script_context.html#a22e3c351fe6b13ba0a62010dfc305080" title="Returns the line number where the exception occurred.">GetExceptionLineNumber</a>());</div>
<div class="line">}</div>
</div><!-- fragment --><p>If desired, it is also possible to <a class="el" href="classas_i_script_context.html#a4d1f481473df3f7aefccc5bb6904e405">register a callback function</a> that will be called at the moment the exception occurred, before the <a class="el" href="classas_i_script_context.html#a8e52894432737acac2e1a422e496bf84">Execute</a> method returns.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="doc_debug.html">Debugging scripts</a> for information on examining the callstack, and <a class="el" href="doc_addon_helpers.html">GetExceptionInfo</a> for a helper function to get information on exceptions. </dd></dl>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Sun Dec 18 2016 12:35:28 for AngelScript by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.3.1 </li>
  </ul>
</div>
</body>
</html>
